18.5 Creating Citations

User Option: reftex-bibliography-commands

LaTeX commands which specify the BibTeX databases to use with the document.

User Option: reftex-bibfile-ignore-regexps

List of regular expressions to exclude files in \\bibliography{..}. File names matched by any of these regexps will not be parsed. Intended for files which contain only @string macro definitions and the like, which are ignored by RefTeX anyway.

User Option: reftex-default-bibliography

List of BibTeX database files which should be used if none are specified. When reftex-citation is called from a document with neither a ‘\bibliography{...}’ statement nor a thebibliography environment, RefTeX will scan these files instead. Intended for using reftex-citation in non-LaTeX files. The files will be searched along the BIBINPUTS or TEXBIB path.

User Option: reftex-sort-bibtex-matches

Sorting of the entries found in BibTeX databases by reftex-citation. Possible values:

nil          Do not sort entries.
author       Sort entries by author name.
year         Sort entries by increasing year.
reverse-year Sort entries by decreasing year.

User Option: reftex-cite-format

The format of citations to be inserted into the buffer. It can be a string, an alist or a symbol. In the simplest case this is just the string ‘\cite{%l}’, which is also the default. See the definition of reftex-cite-format-builtin for more complex examples.

If reftex-cite-format is a string, it will be used as the format. In the format, the following percent escapes will be expanded.

%l

The BibTeX label of the citation.

%a

List of author names, see also reftex-cite-punctuation.

%2a

Like %a, but abbreviate more than 2 authors like Jones et al.

%A

First author name only.

%e

Works like ‘%a’, but on list of editor names. (‘%2e’ and ‘%E’ work a well).

It is also possible to access all other BibTeX database fields:

%b booktitle     %c chapter        %d edition    %h howpublished
%i institution   %j journal        %k key        %m month
%n number        %o organization   %p pages      %P first page
%r address       %s school         %u publisher  %t title
%v volume        %y year
%B booktitle, abbreviated          %T title, abbreviated

Usually, only ‘%l’ is needed. The other stuff is mainly for the echo area display, and for (setq reftex-comment-citations t).

‘%<’ as a special operator kills punctuation and space around it after the string has been formatted.

A pair of square brackets indicates an optional argument, and RefTeX will prompt for the values of these arguments.

Beware that all this only works with BibTeX database files. When citations are made from the \bibitems in an explicit thebibliography environment, only ‘%l’ is available.

If reftex-cite-format is an alist of characters and strings, the user will be prompted for a character to select one of the possible format strings.

In order to configure this variable, you can either set reftex-cite-format directly yourself or set it to the symbol of one of the predefined styles. The predefined symbols are those which have an association in the constant reftex-cite-format-builtin) E.g.: (setq reftex-cite-format 'natbib).

Hook: reftex-format-cite-function

If non-nil, should be a function which produces the string to insert as a citation. Note that the citation format can also be changed with the variable reftex-cite-format. The function will be called with two arguments, the citation-key and the default-format (taken from reftex-cite-format). It should return the string to insert into the buffer.

User Option: reftex-cite-prompt-optional-args

Non-nil means, prompt for empty optional arguments in cite macros. When an entry in reftex-cite-format ist given with square brackets to indicate optional arguments (for example ‘\\cite[][]{%l}’), RefTeX can prompt for values. Possible values are:

nil     Never prompt for optional arguments
t       Always prompt
maybe   Prompt only if reftex-citation was called with C-u prefix arg

Unnecessary empty optional arguments are removed before insertion into the buffer. See reftex-cite-cleanup-optional-args.

User Option: reftex-cite-cleanup-optional-args

Non-nil means, remove empty optional arguments from cite macros if possible.

User Option: reftex-comment-citations

Non-nil means add a comment for each citation describing the full entry. The comment is formatted according to reftex-cite-comment-format.

User Option: reftex-cite-comment-format

Citation format used for commented citations. Must not contain ‘%l’. See the variable reftex-cite-format for possible percent escapes.

User Option: reftex-cite-punctuation

Punctuation for formatting of name lists in citations. This is a list of 3 strings.

1. normal names separator, like ‘, ’ in Jones, Brown and Miller
2. final names separator, like ‘ and ’ in Jones, Brown and Miller
3. The ‘et al.’ string, like ‘ {\it et al.}’ in Jones {\it et al.}

Normal Hook: reftex-select-bib-mode-hook

Normal hook which is run when a selection buffer enters reftex-select-bib-mode.

Keymap: reftex-select-bib-map

The keymap which is active in the citation-key selection process (see Creating Citations).

User Option: reftex-cite-key-separator

String used to separate several keys in a single ‘\\cite’ macro. Per default this is ‘","’ but if you often have to deal with a lot of entries and need to break the macro across several lines you might want to change it to ‘", "’.

User Option: reftex-create-bibtex-header

Header to insert in BibTeX files generated by reftex-create-bibtex-file.

User Option: reftex-create-bibtex-footer

Footer to insert in BibTeX files generated by reftex-create-bibtex-file.